aPLib - Compression

Compression

The following is a description of the aPLib compression functionality.

#### Compression Functions

    size_t aP_pack( const void *source,
                    void *destination,
                    size_t length,
                    void *workmem,
                    int (*callback)(size_t, size_t, size_t, void *),
                    void *cbparam );

Compresses `length` bytes of data from `source[]` into `destination[]`, using `workmem[]` for temporary storage.

The `destination[]` buffer should be large enough to hold `aP_max_packed_size(length)` bytes.

The `workmem[]` buffer should be `aP_workmem_size(length)` bytes large.

The callback function, `callback`, must take four parameters. The first is `length`, the second is the number of input bytes that has been compressed, the third is how many output bytes they have been compressed to, and the fourth is `cbparam`. If you do not have a callback, use `NULL` instead. If the callback returns a non-zero value then `aP_pack` will continue compressing -- if it returns zero, `aP_pack` will stop and return `APLIB_ERROR`.

Parameters:
  `source` - pointer to the data to be compressed.
  `destination` - pointer to where the compressed data should be stored.
  `length` - the length of the uncompressed data in bytes.
  `workmem` - pointer to the work memory which is used during compression.
  `callback` - pointer to the callback function (or `NULL`).
  `cbparam` - callback argument.
Returns:
  the length of the compressed data, or `APLIB_ERROR` on error.

    size_t aP_workmem_size( size_t input_size );

Computes the required size of the `workmem[]` buffer used by `aP_pack` for compressing `input_size` bytes of data.

The current code always returns 640k (640*1024).

Parameters:
  `input_size` - the length of the uncompressed data in bytes.
Returns:
  the required length of the work buffer.

    size_t aP_max_packed_size( size_t input_size );

Computes the maximum possible compressed size possible when compressing `input_size` bytes of incompressible data.

The current code returns `(input_size + (input_size / 8) + 64)`.

Parameters:
  `input_size` - the length of the uncompressed data in bytes.
Returns:
  the maximum possible size of the compressed data.

#### Safe Wrapper Functions

    size_t aPsafe_pack( const void *source,
                        void *destination,
                        size_t length,
                        void *workmem,
                        int (*callback)(size_t, size_t, size_t, void *),
                        void *cbparam );

Wrapper function for `aP_pack`, which adds a header to the compressed data containing the length of the original data, and CRC32 checksums of the original and compressed data.

Parameters:
  `source` - pointer to the data to be compressed.
  `destination` - pointer to where the compressed data should be stored.
  `length` - the length of the uncompressed data in bytes.
  `workmem` - pointer to the work memory which is used during compression.
  `callback` - pointer to the callback function (or `NULL`).
  `cbparam` - callback argument.
Returns:
  the length of the compressed data, or `APLIB_ERROR` on error.
See Also:
  `aP_pack`

#### Example

       /* allocate workmem and destination memory */
       char *workmem    = malloc(aP_workmem_size(length));
       char *compressed = malloc(aP_max_packed_size(length));

       /* compress data[] to compressed[] */
       size_t outlength = aPsafe_pack(data, compressed, length, workmem, NULL, NULL);

       /* if APLIB_ERROR is returned, and error occured */
       if (outlength == APLIB_ERROR) {
          printf("An error occured!\n");
       }
       else {
          printf("Compressed %u bytes to %u bytes\n", length, outlength);
       }

<< prev | home | next >>